IRIX Base Documentation 2001 May

home *** CD-ROM | disk | FTP | other *** search

/ IRIX Base Documentation 2001 May / SGI IRIX Base Documentation 2001 May.iso / usr / share / catman / p_man / cat4 / mload.z / mload

Wrap

Text File | 1998-10-20 | 28.7 KB | 595 lines

mmmmllllooooaaaadddd((((4444)))) mmmmllllooooaaaadddd((((4444)))) NNNNAAAAMMMMEEEE mload - dynamically loadable kernel modules DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN IRIX supports dynamic loading and unloading of modules into a running kernel. Kernel modules can be registered and then loaded automatically by the kernel when the corresponding device is opened, or they can be loaded manually. Similarly, dynamically loaded modules can be unloaded automatically or manually if the module includes an uuuunnnnllllooooaaaadddd entry point. A loadable kernel module can be a character, block or streams device driver, a streams module, a library module or the _i_d_b_g._o module. MMMMoooodddduuuulllleeee CCCCoooonnnnffffiiiigggguuuurrrraaaattttiiiioooonnnn Each loadable module should contain the string: _cccc_hhhh_aaaa_rrrr _****_p_r_e_f_i_x_mmmm_vvvv_eeee_rrrr_ssss_iiii_oooo_nnnn _==== _MMMM______VVVV_EEEE_RRRR_SSSS_IIII_OOOO_NNNN_;;;; M_VERSION is defined in the _m_l_o_a_d._h header file, which should be included by the loadable module. A number of _c_c flags must be defined correctly when compiling loadable modules for Irix. To ensure that you get the correct flags, use the sample makefile in /var/sysgen/Makefile.kernloadio from the eoe.hdr.lib subsystem. Instructions for using the makefile are at the beginning of the Makefile.kernloadio file. A loadable module must not be dependent on any loadable module, other than a library module. In order to load a module comprised of multiple object files, the object files should be linked together into a single object file, using the following _l_d options: ----GGGG0000 ----rrrr ----dddd LLLLooooaaaaddddiiiinnnngggg aaaa DDDDyyyynnnnaaaammmmiiiiccccaaaallllllllyyyy LLLLooooaaaaddddaaaabbbblllleeee KKKKeeeerrrrnnnneeeellll MMMMoooodddduuuulllleeee Either _l_b_o_o_t or the _m_l command can be used to load, register, unload, unregister, and list loadable kernel modules. The _l_b_o_o_t command parses module type, prefix and major number information from the module's master file found in the /_v_a_r/_s_y_s_g_e_n/_m_a_s_t_e_r._d directory. The loadable object file is expected to be found in the /_v_a_r/_s_y_s_g_e_n/_b_o_o_t directory. The _m_l command also provides a means of loading, registering and unloading loadable modules, without the need for creating a master file or reconfiguring the kernel. Load When a module is loaded, the object file's header is read; memory is allocated for the module's text, data and bss; the module's text and data are read; the module's text and data are relocated and unresolved references into the kernel are resolved; a symbol table is created for the module; the module is added to the appropriate kernel switch table; and the module's init routine is called. A module is loaded using the following _m_l command: _mmmm_llll _llll_dddd [_----_vvvv] _----[_cccc_bbbb_BBBB_ffff_mmmm_iiii] _m_o_d_u_l_e._o _----_pppp _p_r_e_f_i_x [_----_ssss _m_a_j_o_r _m_a_j_o_r ...] PPPPaaaaggggeeee 1111 mmmmllllooooaaaadddd((((4444)))) mmmmllllooooaaaadddd((((4444)))) [_----_aaaa _m_o_d_n_a_m_e] If a module is loaded successfully, an id number is returned which can be used to unload the module. A module can also be loaded using _l_b_o_o_t: _llll_bbbb_oooo_oooo_tttt _----_LLLL _m_a_s_t_e_r Register The register command is used to register a module for loading when its corresponding device is opened. When a module is registered, a stub routine is entered into the appropriate kernel switch table. When the corresponding device is opened, the module is actually loaded. A module is registered using the following _m_l command: _mmmm_llll _rrrr_eeee_gggg [_----_vvvv] _----[_cccc_bbbb_BBBB_ffff_mmmm_iiii] _m_o_d_u_l_e._o _----_pppp _p_r_e_f_i_x [_----_ssss _m_a_j_o_r _m_a_j_o_r ...] [_----_aaaa _m_o_d_n_a_m_e] [_----_tttt _a_u_t_o_u_n_l_o_a_d__d_e_l_a_y] If a module is registered successfully, an id number is returned which can be used to unregister the module. A module can also be registered using _l_b_o_o_t: _llll_bbbb_oooo_oooo_tttt _----_RRRR _m_a_s_t_e_r Unload A module can be unloaded only if it provides an uuuunnnnllllooooaaaadddd entry point. A module is unloaded using: _mmmm_llll _uuuu_nnnn_llll_dddd _i_d [_i_d _i_d ...] or _llll_bbbb_oooo_oooo_tttt _----_UUUU _i_d [_i_d _i_d ...] Unregister A module can be unregistered using: _mmmm_llll _uuuu_nnnn_rrrr_eeee_gggg _i_d [_i_d _i_d ...] or _llll_bbbb_oooo_oooo_tttt _----_WWWW _i_d [_i_d _i_d ...] List All loaded and/or registered modules can be listed using: _mmmm_llll _llll_iiii_ssss_tttt [_----_rrrr_llll_bbbb] PPPPaaaaggggeeee 2222 mmmmllllooooaaaadddd((((4444)))) mmmmllllooooaaaadddd((((4444)))) or _llll_bbbb_oooo_oooo_tttt _----_VVVV MMMMaaaasssstttteeeerrrr FFFFiiiilllleeee CCCCoooonnnnffffiiiigggguuuurrrraaaattttiiiioooonnnn If a dynamically loadable module has an associated master file, the master file should include a dddd in Field 1. The dddd flag indicates to _l_b_o_o_t that the module is a dynamically loadable kernel module. If the dddd flag is present _l_b_o_o_t will parse the module's master file, but will not fill in the entry in the corresponding kernel switch table for the module. All global data defined in the master file will be included in the generated _m_a_s_t_e_r._c file. The kernel should be configured with master files that contain the dddd option for each module that will be a dynamically loadable module, if _l_b_o_o_t will be used to load, register, unload, unregister or autoregister the module. If the _m_l(1M) command will be used, then it is not necessary to create a master file for the module. AAAAuuuuttttoooo RRRReeeeggggiiiissssttttrrrraaaattttiiiioooonnnn Loadable modules can be registered by _l_b_o_o_t automatically at system startup when autoconfig is run. In order for a module to be auto- registered, its master file should contain an RRRR in Field 1, in addition to dddd, which indicates that the module is loadable. When _l_b_o_o_t runs at system startup, it registers each module that contains an RRRR in its master file. Modules which specify a particular major number are registered before modules which pick a major number dynamically. If an rc2 script is added, which registers or loads dynamically loadable modules, it should be run after the autoconfig rc2 script is run. For more detailed information, see the _l_b_o_o_t(1M), _m_l(1M), and _m_a_s_t_e_r(4) reference pages. AAAAuuuuttttoooo UUUUnnnnllllooooaaaadddd All registered modules that include an uuuunnnnllllooooaaaadddd routine are automatically unloaded after last close, unless they have been configured not to. Modules are unloaded five minutes after last close by default. The default auto-unload delay can be changed by using _s_y_s_t_u_n_e to change the _m_o_d_u_l_e__u_n_l_d__d_e_l_a_y variable. For more information about systune, see the _s_y_s_t_u_n_e(1M) reference page. A particular module can be configured with a specific auto-unload delay by using the _m_l command. A module can be configured to not be auto-unloaded by either placing an NNNN in the flags field of its _m_a_s_t_e_r._d file, if it is registered using _l_b_o_o_t, or by using _m_l to register the module and using the ----tttt option. KKKKeeeerrrrnnnneeeellll CCCCoooonnnnffffiiiigggguuuurrrraaaattttiiiioooonnnn A kernel which supports loadable modules, should be configured so that the kernel switch tables generated by _l_b_o_o_t(1M) contain "extra" entries for the loadable modules. Extra entries are generated by _l_b_o_o_t based on the values of the following kernel tuneable parameters: PPPPaaaaggggeeee 3333 mmmmllllooooaaaadddd((((4444)))) mmmmllllooooaaaadddd((((4444)))) * name default minimum maximum bbbbddddeeeevvvvsssswwww____eeeexxxxttttrrrraaaa 21 1 254 ccccddddeeeevvvvsssswwww____eeeexxxxttttrrrraaaa 23 3 254 ffffmmmmooooddddsssswwww____eeeexxxxttttrrrraaaa 20 0 vvvvffffsssssssswwww____eeeexxxxttttrrrraaaa 5 0 These tuneable parameters are found in the kernel /_v_a_r/_s_y_s_g_e_n/_m_t_u_n_e/_k_e_r_n_e_l file and are set to the defaults listed above. For more information about changing tuneable parameters, see the _m_t_u_n_e(4) and _s_y_s_t_u_n_e(1M) reference pages. MMMMoooodddduuuulllleeee EEEEnnnnttttrrrryyyy PPPPooooiiiinnnnttttssss Loadable device drivers should conform to the SVR4 DDI/DKI standard. In addition to the entry points specified by the DDI/DKI standard, if a loadable module is to be unloaded, the module needs to contain an uuuunnnnllllooooaaaadddd entry point: _iiii_nnnn_tttt _p_r_e_f_i_x_uuuu_nnnn_llll_oooo_aaaa_dddd _((((_vvvv_oooo_iiii_dddd_)))) An uuuunnnnllllooooaaaadddd routine should be treated as an interrupt routine and should not call any routines that would cause it to sleep, such as: bbbbiiiioooowwwwaaaaiiiitttt(), sssslllleeeeeeeepppp(), ppppsssseeeemmmmaaaa() or ddddeeeellllaaaayyyy(). An uuuunnnnllllooooaaaadddd routine should free any resources allocated by the driver, including freeing interrupt vectors and allocated memory and return 0. MMMMoooodddduuuulllleeee IIIInnnniiiittttiiiiaaaalllliiiizzzzaaaattttiiiioooonnnn After a module is loaded, linked into the kernel and sanity checking is done, the modules' initialization routines, _p_r_e_f_i_xiiiinnnniiiitttt(), _p_r_e_f_i_xeeeeddddttttiiiinnnniiiitttt() and _p_r_e_f_i_xssssttttaaaarrrrtttt() are called, if they exist. For more information on these routines, refer to the SVR4 DDI/DKI Reference Manual and the _I_R_I_X _D_e_v_i_c_e _D_r_i_v_e_r _P_r_o_g_r_a_m_m_e_r'_s _G_u_i_d_e. EEEEddddtttt TTTTyyyyppppeeee DDDDrrrriiiivvvveeeerrrrssss For drivers that have an edtinit entry point, which get passed a pointer to an edt structure, _l_b_o_o_t must be used to load the driver. A vector line should be added to the system file for the driver, as it would for any driver. When the module is loaded, using _l_b_o_o_t, _l_b_o_o_t parses the vector line from the system file to create an edt structure which is passed through the kernel and to the driver's edtinit routine. For more information, see the _s_y_s_t_e_m(4) reference page. LLLLiiiibbbbrrrraaaarrrryyyy MMMMoooodddduuuulllleeeessss A library module is a loadable module which contains a collection of functions and data that other loaded modules can link against. A library module can be loaded using the following _m_l command: _mmmm_llll _llll_dddd [_----_vvvv] _----_llll _l_i_b_r_a_r_y._o A library module must be loaded before other modules that link against it are loaded. Library modules can not be unloaded, registered or unregistered. Only regular object files are supported as loadable PPPPaaaaggggeeee 4444 mmmmllllooooaaaadddd((((4444)))) mmmmllllooooaaaadddd((((4444)))) library modules. TTTThhhheeee iiiiddddbbbbgggg....oooo MMMMoooodddduuuulllleeee The _i_d_b_g._o module can be dynamically loaded into a running kernel, so that the kernel print utility, _i_d_b_g(1M), can be used without reconfiguring and rebooting a new kernel. The _i_d_b_g._o module can be dynamically loaded using the _m_l command: _mmmm_llll _llll_dddd _----_iiii _////_vvvv_aaaa_rrrr_////_ssss_yyyy_ssss_gggg_eeee_nnnn_////_bbbb_oooo_oooo_tttt_////_iiii_dddd_bbbb_gggg_...._oooo _----_pppp _iiii_dddd_bbbb_gggg The _i_d_b_g._o module can also be unloaded. Other idbg modules, such as _x_f_s_i_d_b_g._o, _x_l_v_i_d_b_g._o, _m_l_o_a_d_i_d_b_g._o, and so on, can be loaded after _i_d_b_g._o is loaded. For example: _mmmm_llll _llll_dddd _----_iiii _////_vvvv_aaaa_rrrr_////_ssss_yyyy_ssss_gggg_eeee_nnnn_////_bbbb_oooo_oooo_tttt_////_xxxx_ffff_ssss_iiii_dddd_bbbb_gggg_...._oooo _----_pppp _xxxx_ffff_ssss_iiii_dddd_bbbb_gggg_...._oooo For more information, see the _i_d_b_g(1M) reference page. LLLLooooaaaaddddaaaabbbblllleeee MMMMoooodddduuuulllleeeessss aaaannnndddd HHHHaaaarrrrddddwwwwaaaarrrreeee IIIInnnnvvvveeeennnnttttoooorrrryyyy Many device drivers add to the hardware inventory in their init or edtinit routines. If a driver is a dynamically loadable driver and is auto-registered, it will not show up in the hardware inventory until the driver has been loaded on the first open of the corresponding device. If a clean install or a diskless install is done, a /_d_e_v entry will not get created by _M_A_K_E_D_E_V for such a driver since it doesn't appear in the hardware inventory. If such a situation arises, the DDDD _m_a_s_t_e_r._d flag can be used to indicate that the driver should be loaded, then unloaded by _a_u_t_o_c_o_n_f_i_g. If the RRRR _m_a_s_t_e_r._d flag, which indicates that the driver should be auto-registered, is also used, then the driver will be auto- registered as usual. A startup script can then be added that will run _M_A_K_E_D_E_V after _a_u_t_o_c_o_n_f_i_g, if necessary. For an example, see the /_e_t_c/_i_n_i_t._d/_c_h_k_d_e_v startup script. KKKKeeeerrrrnnnneeeellll RRRRuuuunnnnttttiiiimmmmeeee SSSSyyyymmmmbbbboooollll TTTTaaaabbbblllleeee A runtime symbol table which contains kernel routines and global data that modules can link against is created from the ELF symbol information in the kernel that was booted. The runtime symbol table is created automatically by the kernel from the file indicated by the kkkkeeeerrrrnnnnnnnnaaaammmmeeee environment variable, which is set by sash to the name of the file that was booted. The symbol table is loaded with a default auto-unload timeout of five minutes, after which the symbol table is automatically unloaded. The symbol table is automatically reloaded when needed to resolve symbols (for example when a new or registered module is loaded). The kernel runtime symbol table can also be loaded manually, using the _m_l command: PPPPaaaaggggeeee 5555 mmmmllllooooaaaadddd((((4444)))) mmmmllllooooaaaadddd((((4444)))) _mmmm_llll _llll_dddd _----_rrrr _////_uuuu_nnnn_iiii_xxxx Or unloaded manually: _mmmm_llll _uuuu_nnnn_llll_dddd _i_d Note that only one kernel runtime symbol table can exist at one time. Auto-loading and unloading of the kernel runtime symbol table can be disabled using the mmmmllllooooaaaadddd____aaaauuuuttttoooo____rrrrttttssssyyyymmmmssss systune variable. For more information about tuneable variables, see the _s_y_s_t_u_n_e(1M) reference page. DDDDeeeebbbbuuuuggggggggiiiinnnngggg LLLLooooaaaaddddaaaabbbblllleeee MMMMoooodddduuuulllleeeessss _s_y_m_m_o_n(1M) supports debugging of loadable modules. _s_y_m_m_o_n commands that do a symbol table lookup, such as: brk, lkup, lkaddr, hx and nm, also search the symbol tables created for loadable modules. The _m_s_y_m_s command can also be used to list the symbols for a particular loaded module: _mmmm_ssss_yyyy_mmmm_ssss _i_d The _m_l_i_s_t command can be used to list all of the modules that are currently loaded and/or registered. For more information, see the _s_y_m_m_o_n(1M) reference page. LLLLooooaaaadddd////RRRReeeeggggiiiisssstttteeeerrrr FFFFaaaaiiiilllluuuurrrreeeessss If a registered module fails to load, it is suggested that the module be unregistered and then loaded using mmmmllll lllldddd or llllbbbbooooooootttt ----LLLL, in order to get a more detailed error message about the failure. All of the error codes, including a description of each, are listed in the _m_l_o_a_d._h header file, found in the /_u_s_r/_i_n_c_l_u_d_e/_s_y_s directory. The kernel will fail to load or register a module for any of the following reasons: 1. If autoconfig is not run at system startup, none of the dynamically loadable modules will be registered or loaded. 2. If autoconfig fails for some reason, before it has processed the dynamically loadable module _m_a_s_t_e_r._d files, the modules will not be registered or loaded. 3. The major number specified either in the master file, or by the ml command, is already in use. 4. The object file is not compiled with the correct options, such as ----GGGG0000 and ----jjjjaaaallllrrrr. 5. The module is an "old style" driver, with either xxxdevflag set to D_OLD, or no xxxdevflag exists in the driver. PPPPaaaaggggeeee 6666 mmmmllllooooaaaadddd((((4444)))) mmmmllllooooaaaadddd((((4444)))) 6. A corrupted object file could cause "invalid JMPADDR" errors. 7. Not all of the module's symbols were resolved by the kernel. 8. The device switch table is full and has no more room to add a loadable driver. 9. Required entry points for the particular type of module are not found in the object file, such as xxxopen for a character device driver. 10. All major numbers are in use. 11. An old sash is used to boot the kernel, which does not set the kkkkeeeerrrrnnnnnnnnaaaammmmeeee environment variable, which indicates the on-disk kernel image to load the runtime symbol table from (for example, /_u_n_i_x). This will cause all loadable modules to fail to load or be registered. To find out what the kkkkeeeerrrrnnnnnnnnaaaammmmeeee environment variable is set to, use the _n_v_r_a_m(1M) command: _nnnn_vvvv_rrrr_aaaa_mmmm _kkkk_eeee_rrrr_nnnn_nnnn_aaaa_mmmm_eeee 12. The runtime symbol table can not be loaded from the file indicated by the kkkkeeeerrrrnnnnnnnnaaaammmmeeee environment variable, because the file does not exist, the file is not the same as the running kernel or the kernel was bootp'ed from another machine. EEEEXXXXAAAAMMMMPPPPLLLLEEEE 1111 The following example lists the steps necessary to build a kernel and load a character device driver, called dlkm, using the _l_b_o_o_t command: 1. Add dddd to the dlkm master file: *FLAG PREFIX SOFT #DEV DEPENDENCIES cd dlkm 38 2 2. Make sure that the cdevsw_extra kernel tuneable parameter allows for extra entries in the cdevsw table, the default setting in /_v_a_r/_s_y_s_g_e_n/_m_t_u_n_e/_k_e_r_n_e_l is: cdevsw_extra 23 3 254 The _s_y_s_t_u_n_e(1M) command also lists the current values of all of the tuneable parameters. If the kernel is not configured to allow extra entries in the cdevsw table, use the _s_y_s_t_u_n_e command to change the cdevsw_extra parameter: > _ssss_yyyy_ssss_tttt_uuuu_nnnn_eeee _----_iiii _ssss_yyyy_ssss_tttt_uuuu_nnnn_eeee_----_>>>> _cccc_dddd_eeee_vvvv_ssss_wwww______eeee_xxxx_tttt_rrrr_aaaa _3333 _ssss_yyyy_ssss_tttt_uuuu_nnnn_eeee_----_>>>> _qqqq_uuuu_iiii_tttt _>>>> PPPPaaaaggggeeee 7777 mmmmllllooooaaaadddd((((4444)))) mmmmllllooooaaaadddd((((4444)))) 3. Build a new kernel and boot the target system with the new kernel. 4. Compile the _d_l_k_m._c driver. It should be noted that linking either 64bit or 32bit objects the "-non_shared" flag is not needed. For 32-bit modules: _cccc_cccc _----_nnnn_oooo_nnnn______ssss_hhhh_aaaa_rrrr_eeee_dddd _----_eeee_llll_ffff _----_GGGG_0000 _----_rrrr _----_dddd _----_jjjj_aaaa_llll_rrrr _----_cccc _dddd_llll_kkkk_mmmm_...._cccc For 64-bit modules: _cccc_cccc _----_nnnn_oooo_nnnn______ssss_hhhh_aaaa_rrrr_eeee_dddd _----_eeee_llll_ffff _----_GGGG _0000 _----_jjjj_aaaa_llll_rrrr _----_cccc _dddd_llll_kkkk_mmmm_...._cccc 5. Copy _d_l_k_m._o to /_v_a_r/_s_y_s_g_e_n/_b_o_o_t. 6. Load the driver into the kernel: _llll_bbbb_oooo_oooo_tttt _----_LLLL _dddd_llll_kkkk_mmmm 7. List the currently loaded modules to verify that the module was loaded: _llll_bbbb_oooo_oooo_tttt _----_VVVV EEEEXXXXAAAAMMMMPPPPLLLLEEEE 2222 The following example lists the steps necessary to load a character device driver, called dlkm, using the _m_l command: 1. Follow step 2 from example 1. 2. Follow step 4 from example 1. 3. Load the driver into the kernel: _mmmm_llll _llll_dddd _----_cccc _dddd_llll_kkkk_mmmm_...._oooo _----_pppp _dddd_llll_kkkk_mmmm _----_ssss _3333_8888 If a major number is not specified, the first free major number in the MAJOR table is used. If the load was successful, an id number is returned, which can be used to unload the driver. 4. List the currently loaded modules to verify that the module was loaded: _mmmm_llll _llll_iiii_ssss_tttt CCCCAAAAVVVVEEEEAAAATTTTSSSS 1. Loadable modules must not have any dependencies on loadable modules, other than library modules. When a module is loaded, it is linked against the kernel symbol table and any loaded library modules' symbol tables, but it is not linked against other modules' symbol tables. PPPPaaaaggggeeee 8888 mmmmllllooooaaaadddd((((4444)))) mmmmllllooooaaaadddd((((4444)))) 2. Only character, block and streams device drivers, streams modules and library modules are supported as loadable modules at this time. 3. Old style drivers (devflag set to D_OLD) are not loadable. 4. Kernel profiling does not support loadable modules. 5. Memory allocated may be in either K0SEG or in K2SEG. If the module is loaded into K2SEG static buffers are not necessarily in physically contiguous memory. Also, depending on machine configuration, K2SEG addresses may map to high physical memory addresses, in which case, PHYS_TO_K0 and PHYS_TO_K1 macros will not work. SSSSEEEEEEEE AAAALLLLSSSSOOOO cc(1), lboot(1M), ld(1), ml(1M), symmon(1M), systune(1M), master(4), mtune(4). _I_R_I_X _D_e_v_i_c_e _D_r_i_v_e_r _P_r_o_g_r_a_m_m_e_r'_s _G_u_i_d_e PPPPaaaaggggeeee 9999